home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / dmedia / dmGetUST.z / dmGetUST
Encoding:
Text File  |  2002-10-03  |  5.4 KB  |  133 lines
  1.  
  2.  
  3.  
  4. ddddmmmmGGGGeeeettttUUUUSSSSTTTT((((3333ddddmmmm))))                                                    ddddmmmmGGGGeeeettttUUUUSSSSTTTT((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ddddmmmmGGGGeeeettttUUUUSSSSTTTT, ddddmmmmGGGGeeeettttUUUUSSSSTTTTCCCCuuuurrrrrrrreeeennnnttttTTTTiiiimmmmeeeePPPPaaaaiiiirrrr - get digital media Unadjusted System
  10.      Time (UST)
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ddddmmmmeeeeddddiiiiaaaa....hhhh>>>>
  14.      LLLLiiiinnnnkkkk wwwwiiiitttthhhh ----llllddddmmmmeeeeddddiiiiaaaa
  15.  
  16.      iiiinnnntttt ddddmmmmGGGGeeeettttUUUUSSSSTTTT((((uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg lllloooonnnngggg ****uuuusssstttt))))
  17.      iiiinnnntttt ddddmmmmGGGGeeeettttUUUUSSSSTTTTCCCCuuuurrrrrrrreeeennnnttttTTTTiiiimmmmeeeePPPPaaaaiiiirrrr((((uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg lllloooonnnngggg ****uuuusssstttt,,,,
  18.                                  ssssttttrrrruuuucccctttt ttttiiiimmmmeeeevvvvaaaallll ****ttttvvvv))))
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      ddddmmmmGGGGeeeettttUUUUSSSSTTTT(3dm) returns a high-resolution, unsigned 64-bit number to
  22.      processes using libdmedia. The value of UST is the number of nanoseconds
  23.      since the system was booted. Though the resolution is 1 nanosecond, the
  24.      actual accuracy may be somewhat lower and varies from system to system.
  25.      Unlike other representations of time under UNIX, the value from which
  26.      this timestamp derives is never adjusted; therefore it is guaranteed to
  27.      be monotonically increasing.
  28.  
  29.      Typically, the UST is used as a timestamp; that is, it is paired with a
  30.      specific item or location in a digital media stream. Normally,
  31.      ddddmmmmGGGGeeeettttUUUUSSSSTTTT(3dm) is nnnnooootttt used to do this; each medium has its own method for
  32.      obtaining these timestamps. For example, the UST associated with an audio
  33.      sample frame number can be obtained using the AAAALLLLggggeeeettttffffrrrraaaammmmeeeettttiiiimmmmeeee((((3333AAAA)))) call,
  34.      and the UST associated with a video buffer can be obtained using the
  35.      vvvvllllGGGGeeeettttUUUUSSSSTTTTMMMMSSSSCCCCPPPPaaaaiiiirrrr((((3333ddddmmmm)))) call.  In the MIDI and tserialio libraries, UST
  36.      stamps are paired with bytes of data which came in or will go out a
  37.      serial port.
  38.  
  39.      The function ddddmmmmGGGGeeeettttUUUUSSSSTTTTCCCCuuuurrrrrrrreeeennnnttttTTTTiiiimmmmeeeePPPPaaaaiiiirrrr(3dm) returns a UST measurement and a
  40.      time of day measurement (see ggggeeeettttttttiiiimmmmeeeeooooffffddddaaaayyyy(3)) which represent the same
  41.      instant of time.  This is often useful for relating the UST clocks of two
  42.      different machines.  The usefulness of this function is limited by the
  43.      reliability of the UNIX time of day clock, which (unlike the UST clock)
  44.      can be adjusted by system administrators and network time daemons.
  45.  
  46. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  47.      Both functions return 0 if successful or -1 on error.
  48.  
  49. NNNNOOOOTTTTEEEESSSS
  50.      Although this function returns an unsigned 64 bit number, most libraries
  51.      which manipulate UST (and MSC where appropriate) use the stamp_t symbol,
  52.      which is defined as a signed 64-bit number.  The signed representation is
  53.      generally more convenient, since USTs and MSCs are most often used in
  54.      signed arithmetic calculations.  We recommend that you cast the value
  55.      returned by ddddmmmmGGGGeeeettttUUUUSSSSTTTT(3dm) directly into a stamp_t, as in:
  56.         stamp_t now;
  57.         dmGetUST((unsigned long long *)(&now));
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ddddmmmmGGGGeeeettttUUUUSSSSTTTT((((3333ddddmmmm))))                                                    ddddmmmmGGGGeeeettttUUUUSSSSTTTT((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      The period of the 64-bit unsigned UST clock is 584 years, and the period
  75.      of the signed 64-bit UST clock is 292 years, so practical code need not
  76.      concern itself with UST wrap in either case.
  77.  
  78. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  79.      ALintro(3A), ALgetframetime(3A), mdSetOrigin(3dm), mdSend(3dm),
  80.      mdReceive(3dm), mdIntro(3dm), vlGetUSTMSCPair(3dm), tserialio(3)
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.